home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / mann / regexp.n < prev    next >
Text File  |  1994-09-20  |  11KB  |  342 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/regexp.n,v 1.4 93/08/03 16:37:28 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS regexp tcl
  206. .BS
  207. '\" Note:  do not modify the .SH NAME line immediately below!
  208. .SH NAME
  209. regexp \- Match a regular expression against a string
  210. .SH SYNOPSIS
  211. \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR?
  212. .BE
  213.  
  214. .SH DESCRIPTION
  215. .PP
  216. Determines whether the regular expression \fIexp\fR matches part or
  217. all of \fIstring\fR and returns 1 if it does, 0 if it doesn't.
  218. .LP
  219. If additional arguments are specified after \fIstring\fR then they
  220. are treated as the names of variables in which to return
  221. information about which part(s) of \fIstring\fR matched \fIexp\fR.
  222. \fIMatchVar\fR will be set to the range of \fIstring\fR that
  223. matched all of \fIexp\fR.  The first \fIsubMatchVar\fR will contain
  224. the characters in \fIstring\fR that matched the leftmost parenthesized
  225. subexpression within \fIexp\fR, the next \fIsubMatchVar\fR will
  226. contain the characters that matched the next parenthesized
  227. subexpression to the right in \fIexp\fR, and so on.
  228. .LP
  229. If the initial arguments to \fBregexp\fR start with \fB\-\fR then
  230. .VS
  231. they are treated as switches.  The following switches are
  232. currently supported:
  233. .TP 10
  234. \fB\-nocase\fR
  235. Causes upper-case characters in \fIstring\fR to be treated as
  236. lower case during the matching process.
  237. .TP 10
  238. \fB\-indices\fR
  239. Changes what is stored in the \fIsubMatchVar\fRs. 
  240. Instead of storing the matching characters from \fBstring\fR,
  241. each variable
  242. will contain a list of two decimal strings giving the indices
  243. in \fIstring\fR of the first and last characters in the matching
  244. range of characters.
  245. .TP 10
  246. \fB\-\|\-\fR
  247. Marks the end of switches.  The argument following this one will
  248. be treated as \fIexp\fR even if it starts with a \fB\-.
  249. .VE
  250. .LP
  251. If there are more \fIsubMatchVar\fR's than parenthesized
  252. subexpressions within \fIexp\fR, or if a particular subexpression
  253. in \fIexp\fR doesn't match the string (e.g. because it was in a
  254. portion of the expression that wasn't matched), then the corresponding
  255. \fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
  256. has been specified or to an empty string otherwise.
  257.  
  258. .SH "REGULAR EXPRESSIONS"
  259. .PP
  260. Regular expressions are implemented using Henry Spencer's package
  261. (thanks, Henry!),
  262. and much of the description of regular expressions below is copied verbatim
  263. from his manual entry.
  264. .PP
  265. A regular expression is zero or more \fIbranches\fR, separated by ``|''.
  266. It matches anything that matches one of the branches.
  267. .PP
  268. A branch is zero or more \fIpieces\fR, concatenated.
  269. It matches a match for the first, followed by a match for the second, etc.
  270. .PP
  271. A piece is an \fIatom\fR possibly followed by ``*'', ``+'', or ``?''.
  272. An atom followed by ``*'' matches a sequence of 0 or more matches of the atom.
  273. An atom followed by ``+'' matches a sequence of 1 or more matches of the atom.
  274. An atom followed by ``?'' matches a match of the atom, or the null string.
  275. .PP
  276. An atom is a regular expression in parentheses (matching a match for the
  277. regular expression), a \fIrange\fR (see below), ``.''
  278. (matching any single character), ``^'' (matching the null string at the
  279. beginning of the input string), ``$'' (matching the null string at the
  280. end of the input string), a ``\e'' followed by a single character (matching
  281. that character), or a single character with no other significance
  282. (matching that character).
  283. .PP
  284. A \fIrange\fR is a sequence of characters enclosed in ``[]''.
  285. It normally matches any single character from the sequence.
  286. If the sequence begins with ``^'',
  287. it matches any single character \fInot\fR from the rest of the sequence.
  288. If two characters in the sequence are separated by ``\-'', this is shorthand
  289. for the full list of ASCII characters between them
  290. (e.g. ``[0-9]'' matches any decimal digit).
  291. To include a literal ``]'' in the sequence, make it the first character
  292. (following a possible ``^'').
  293. To include a literal ``\-'', make it the first or last character.
  294.  
  295. .SH "CHOOSING AMONG ALTERNATIVE MATCHES"
  296. .PP
  297. In general there may be more than one way to match a regular expression
  298. to an input string.  For example, consider the command
  299. .DS
  300. \fBregexp  (a*)b*  aabaaabb  x  y
  301. .DE
  302. Considering only the rules given so far, \fBx\fR and \fBy\fR could
  303. end up with the values \fBaabb\fR and \fBaa\fR, \fBaaab\fR and \fBaaa\fR,
  304. \fBab\fR and \fBa\fR, or any of several other combinations.
  305. To resolve this potential ambiguity \fBregexp\fR chooses among
  306. alternatives using the rule ``first then longest''.
  307. In other words, it consders the possible matches in order working
  308. from left to right across the input string and the pattern, and it
  309. attempts to match longer pieces of the input string before shorter
  310. ones.  More specifically, the following rules apply in decreasing
  311. order of priority:
  312. .IP [1]
  313. If a regular expression could match two different parts of an input string
  314. then it will match the one that begins earliest.
  315. .IP [2]
  316. If a regular expression contains \fB|\fR operators then the leftmost
  317. matching sub-expression is chosen.
  318. .IP [3]
  319. In \fB*\fR, \fB+\fR, and \fB?\fR constructs, longer matches are chosen
  320. in preference to shorter ones.
  321. .IP [4]
  322. In sequences of expression components the components are considered
  323. from left to right.
  324. .LP
  325. In the example from above, \fB(a*)b*\fR matches \fBaab\fR:  the \fB(a*)\fR
  326. portion of the pattern is matched first and it consumes the leading
  327. \fBaa\fR; then the \fBb*\fR portion of the pattern consumes the
  328. next \fBb\fR.  Or, consider the following example:
  329. .DS
  330. \fBregexp  (ab|a)(b*)c  abc  x  y  z
  331. .DE
  332. After this command \fBx\fR will be \fBabc\fR, \fBy\fR will be
  333. \fBab\fR, and \fBz\fR will be an empty string.
  334. Rule 4 specifies that \fB(ab|a)\fR gets first shot at the input
  335. string and Rule 2 specifies that the \fBab\fR sub-expression
  336. is checked before the \fBa\fR sub-expression.
  337. Thus the \fBb\fR has already been claimed before the \fB(b*)\fR
  338. component is checked and \fB(b*)\fR must match an empty string.
  339.  
  340. .SH KEYWORDS
  341. match, regular expression, string
  342.